/**
 * 版权所有(C)，上海勾芒信息科技，2017，所有权利保留。
 * 
 * 项目名：	cards-web
 * 文件名：	WxMpCard2Service.java
 * 模块说明：	
 * 修改历史：
 * 2017年3月31日 - Debenson - 创建。
 */
package me.chanjar.weixin.mp.api;

import java.util.List;

import me.chanjar.weixin.common.exception.WxErrorException;
import me.chanjar.weixin.mp.bean.card.AbstractCard;
import me.chanjar.weixin.mp.bean.card.ActivateMemberForm;
import me.chanjar.weixin.mp.bean.card.ActiveMemberRequest;
import me.chanjar.weixin.mp.bean.card.ApplyCardQrCode;
import me.chanjar.weixin.mp.bean.card.ApplyCardQrCodeResult;
import me.chanjar.weixin.mp.bean.card.BaseInfo.CardStatus;
import me.chanjar.weixin.mp.bean.card.Card;
import me.chanjar.weixin.mp.bean.card.Cash;
import me.chanjar.weixin.mp.bean.card.ConsumeCardResult;
import me.chanjar.weixin.mp.bean.card.Coupon;
import me.chanjar.weixin.mp.bean.card.Groupon;
import me.chanjar.weixin.mp.bean.card.Member;
import me.chanjar.weixin.mp.bean.card.MemberInfo;
import me.chanjar.weixin.mp.bean.card.QueryCardResult;
import me.chanjar.weixin.mp.bean.card.UserCards;

/**
 * 卡券相关接口 <br>
 * {@link WxMpCardService}接口不完整，这里补充完整卡券接口。
 * 
 * @author Debenson
 * @since 0.1
 */
public interface WxMpCardxService extends WxMpCardService {

  /**
   * 创建现金券
   *
   * @param cash
   * @return 卡券id.
   * @throws WxErrorException
   */
  public String createCash(Cash cash) throws WxErrorException;

  /**
   * 创建团购券
   *
   * @param groupon
   * @return 卡券id.
   * @throws WxErrorException
   */
  public String createGroupon(Groupon groupon) throws WxErrorException;

  /**
   * 创建优惠券
   *
   * @param coupon
   * @return 卡券id
   * @throws WxErrorException
   */
  public String createCoupon(Coupon coupon) throws WxErrorException;

  /**
   * 创建会员卡
   *
   * @param member
   * @return 卡券id
   * @throws WxErrorException
   */
  public String createMember(Member member) throws WxErrorException;

  /**
   * 创建卡券
   * 
   * @param card
   *          具体的卡券结构体
   * @return 卡券id
   * @throws WxErrorException
   */
  public <C extends AbstractCard> String createCard(C card) throws WxErrorException;

  /**
   * 查询卡券详情
   * 
   * @param cardId
   *          卡券ID
   * @return
   * @throws WxErrorException
   */
  public Card get(String cardId) throws WxErrorException;

  /**
   * 修改卡券库存。
   * 
   * @param cardId
   *          卡券id，禁止为null。
   * @param occur
   *          发生额， 大于0表示增加库存，小于0表示减少库存。
   * @throws WxErrorException
   */
  public void modifystock(String cardId, int occur) throws WxErrorException;

  /**
   * 通过open设置测试使用的白名单
   *
   * @param openIds
   *          测试的openid列表。
   * @throws WxErrorException
   */
  public void setWhiteListByOpenId(String... openIds) throws WxErrorException;

  /**
   * 通过微信号设置测试使用的白名单
   *
   * @param userNames
   *          测试的微信号列表。
   * @throws WxErrorException
   */
  public void setWhiteListByUserName(String... userNames) throws WxErrorException;

  /**
   * 设置测试使用的白名单
   *
   * @param openIds
   *          测试的openid列表。
   * @param userNames
   *          测试的微信号列表。
   * @throws WxErrorException
   */
  public void setWhiteList(List<String> openIds, List<String> userNames) throws WxErrorException;

  /**
   * 批量查询卡券列表
   * 
   * @param offset
   *          查询卡列表的起始偏移量，从0开始，即offset: 5是指从从列表里的第六个开始读取。
   * @param count
   *          需要查询的卡片的数量（数量最大50）。
   * @param statusList
   *          支持开发者拉出指定状态的卡券列表，未传入筛选条件时，该接口默认传回该商户名下所有状态的卡券；
   * @return
   * @throws WxErrorException
   */
  public QueryCardResult query(int offset, int count, CardStatus... statusList)
      throws WxErrorException;

  /**
   * 创建卡券的投放二维码
   * 
   * @param applies
   *          卡券信息。
   * @return 二维码信息。
   * @throws WxErrorException
   */
  public ApplyCardQrCodeResult applyCardQrCode(ApplyCardQrCode... applies) throws WxErrorException;

  /**
   * 导入微信卡券卡号。
   * 
   * @param cardId
   *          需要进行导入code的卡券ID。
   * @param codes
   *          需导入微信卡券后台的自定义code，上限为100个
   * @throws WxErrorException
   */
  public void depositCode(String cardId, List<String> codes) throws WxErrorException;

  /**
   * 查询导入code数目接口
   * 
   * @param cardId
   *          进行导入code的卡券ID
   * @return 已经成功存入的code数目
   * @throws WxErrorException
   */
  public int getDepositCodeCount(String cardId) throws WxErrorException;

  /**
   * 获取用户已领取卡券
   * 
   * @param openId
   *          需要查询的用户openid
   * @param cardId
   *          卡券ID。不填写时默认查询当前appid下的卡券。
   * @return
   * @throws WxErrorException
   */
  public UserCards getUserCards(String openId, String cardId) throws WxErrorException;

  /**
   * 卡券Code核销。核销失败会抛出异常
   *
   * @param code
   *          单张卡券的唯一标准
   * @return
   * @throws WxErrorException
   * @see {@link #consumeCardCode(String)}
   * @see #consumeCardCode(String, String)
   */
  public ConsumeCardResult consumeCard(String code) throws WxErrorException;

  /**
   * 卡券Code核销。核销失败会抛出异常
   *
   * @param code
   *          单张卡券的唯一标准
   * @param cardId
   *          当自定义Code卡券时需要传入card_id，其它传null。
   * @return
   * @throws WxErrorException
   * @see {@link #consumeCardCode(String)}
   * @see #consumeCardCode(String, String)
   */
  public ConsumeCardResult consumeCard(String code, String cardId) throws WxErrorException;

  /**
   * 激活会员卡。
   * 
   * @param request
   * @throws WxErrorException
   */
  public void activeMember(ActiveMemberRequest request) throws WxErrorException;

  /**
   * 设置开卡字段
   * 
   * @param form
   * @throws WxErrorException
   */
  public void setActivateMemberForm(ActivateMemberForm form) throws WxErrorException;

  /**
   * 拉取会员信息
   * 
   * @param code
   *          单张卡券的唯一标准
   * @param cardId
   *          当自定义Code卡券时需要传入card_id，其它传null。
   * @return
   * @throws WxErrorException
   */
  public MemberInfo getMemberInfo(String code, String cardId) throws WxErrorException;

}
